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ThJLs document was pr eparecK^or the Institute for Com- 
puter Sciences and Technology, N&Hpnal Bureau oL Standards, 
by the Federal Computer Perfornja^e Evaluation aj&d Simula- 
tion Center ( FEDSIM) • It is based qn a simijlar document 
originally prepared for use by the U.S. Aif Force in support 
of military 'analyses,. That document has b^eti rea*r,anged , 
exwiplesr^have been changed, and the document had been mad* 
•ore generally applicable so that it may be usdd throughout 
the Federal simulation community. Recommeprdpt ibns for im- 
provements of these guideline's are solicited . it is intend- 
ed that at.ter thorough reviews and trial us^ t 
will be reissued as a Federal Guideline in 
Federal Information -Processing Standards f (FIPS ) 
ments should be directed to: -t 



Institute for Computer Sciences and Technology, 
Programming Science Division 
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I COMPUTER MODEL DOCUMENTATION GUIDE 



This document provides guidelines for prepar-' 
ing* ^documentation for compujter models . Re commend - 
\ ed structures For four types of manuals providing 
model, information for , four different classed of. 
audiences (managers, use rs f analysts , and program- 
mers)" is presented. This dcjcument specifies the 
content of sections and subsections .for each ty.pe 
of manual. Manuals prepared using these guide- 
lines will enable persons interested in a model to 
understand^ the capabilities and 1 iqi tation^ of 
that model. 

Key words: documentation; . manuals; 

m o d e 1^ s f 

-simulation. < • - \ ♦ 

I. INTRODUCTION 

this dr^ft document provifies^'gu^delines for- preparing 
documentation for computet models, as well as complete sub- 
models delivered, separately. The primary goaL of model do- y 
cumentation is to communicate Effectively the details of 
'model. design a<nd* operation tp persons with varying interests 
in 'a model. Since a model's developers are frequently not 
the model's ul t imate , use rs > complete, concise documentation 
' is Essential for ef f 6ct ive '1node 1 use* Documentation should 
Inform analysts familiar with the phenomena being modeled, 
or the modelling techniques employed, of the essential 
features and assumptions of a new model. Throughout its 
life cycle, a model may be used and modified by 'variou? peo- 
ple, making accurate and current documentation of the under-^ 
.lying computer program essential for proper, correct, use and 
maintenance pf the model. Ultimately, model results^may be 
used in a, decision-making environment by individuals who are* 
unfamiliar with the details of modeling and the' associated 
benefits, risks, and costs. 0 In such . s ituat Ions , .mode 1 docu- 
mentation should describe, i'n non-technical terms,, the en- 
vironment in wtrlch* a "model -can b$//use ful , \l imitations on its 
-use, and the manpower, time, and dollar cV>sts* required J>y 
its atfe. . These guideiines recommend- structures and some 
conventions for preparing moxlel document at ibn'^n the form of 
manuals for users/ analysts, programmer A, and managers. 
Each type of manual should provide clear, coWise documenta- 
tion that i»s directed toward an audience w^th a particular 
interest in a model. 



These guidelines devote a section to each type of manu- 
al, i.e., The Managef's Manual, The User's Manual, The 
Programmer's Manual, The Analyst's' Manual. . Each section be- 
gins with a table of content s . that lists .recommended topics 
of interest to users of that manual. Items may be added to 
or* deleted from this 't^ble of contents, however, according 
to individual requirements . The discussion for each manual 
enlarges upon the items required in *each of the sections and 
subsections, as recommended in the table of contents for 
that manual. Terms used >in each manual should-be those 
directed toward that manual's audience.' 

These guidelines are for. models that are used chiefly 
in a decision w making^nvir-enmen t> Thus, th$ main goal of a 
Manager's Manual, is to cassis* managers to' make ^decisions. 
To accomplish this, the Manual must describe the model and 
its application to managers (including the management" that 
sponsored 'the model) who may be interested in using a 
developed capability* The Manual should pr9vide managers 
with -sufficient information to permit them to accurately as- 
sess model ioput requirement s (including ' time, money, and y 
oth^r resources), available outputs, and the accuracy and 
precision of the results. Managers can use'this Manual J.n* 
justifying the employment of ^the roodeH and in evaluating 
subsequent results. " 4 

A user is assumed be interested mainly in depriving 
results from a model for specific applications. The guide- 
-lines recommend • that the User's Manual be organized into ,a 
section for the user and a section for the data technicians 
who will^set-up and run the moddl. To use the model intel- 
ligently, a user mu„st be aware af its logical structure / the 
general simulation approach, and any assumptions and limita- 
tions ^ a f fe c t ing the model/s* applicability . A user need not 
be interested in details of programming or analysis beyond 
the preparation, of input data and the interpretation of 
mQd^l results. r 
• ^ 

Programmers are \ interested primarily in maintaining and 
modifying -a model. A programmer must correct any errors* 
discovered during model usage that, are not attributable to/ 
user-entered data. Pr ogramme r s , especially those re quired 
to convert a model to another computer system, ne'ed to 
understand features of a modal that are installation unique* 
THus/.the Prpgrammer's Manual must provide all the details 
necessary to understand the operation of a model: to debug 
it, to maintain' and modify.it, and to convert the model to 
oth*» computer systems.' 



\ 



These guideline^ assume an analyst; to be ' interested 
primarily in the analytical techniques and algorithms used 
in/a model. An analyst is concerned with the equations used 
in' a model and the methods used for model verification and 
validation* An analyst does not need to know user , details 
such as input and output formats, or programming details in* 
volving language syntax. 

* 

Decisions about which of these manuals are actually re- 
quired^ whether or no* they* should be prepared in separate 
volumes, etc., should be made on, a case-by-case ( Variis. 
Also, a plan should be- developed for documentation updates 
and maintenance; so that these manuals r.ewln current* Such 
issues as the^e should be dealt with early during the model 
planning and development phases, so that r documen tat ion* re- 
quirements actually become .part of the development plaa, 
rather than an afterthought*. Further, applicable documenta*- 
tion produced, using programming conventions should be used 
in conjunction with these guidelines. 

Other ^guidelines prepared specif icaljLy tp support com- 
puter software documen tat ion -are available which may .be used 
in con junction* with this guideline. These documents are : f 

FIPS PUB 30, Software Summary for Describing Computer Pro- 
grams 'and ^Automated Data Systems* It is used , to announce 
computer programs* which are transferable, ajid have br^oad ap- 
plicability* .A* standard' software summary form is defjLnted 
(SF-185), which permits description of the program for iden- 
tification., referenc| and dissemination. This form is used 
by the General Services Administration for registryof' pro- 
grams and for publication^ of program , abstracts i,n the 
Federal Software Exchange Catalog. 



FIPS PUB 38, Guidelines for Documentation* of Computer Pro- 
grams and Automated .Data Systems. It provides guidance to 
documentation content for the development phase, including 
requirements ddcument at ion , system specifications, user, 
operations aftd maintenance manuals, and test/ documentation* 



) FIPS PUB 64^ Guidelines for Documentation of 'Computer Pro- 

grams and Automated Data Sys^Bis for the Initiation Phase* 
This document provides guidance for* project requests, feasi- 
bility studies, and cost benefit analyses; 
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II. .GUIDELINES FOR PREPARING A MANAGER'S, MANUAL 



This section provides a recommended structure x for the 
Manager's Manual and describees the -contents qf each section 
and subsection.' A manual prepared using these guidelines 
will ^provide* descriptions of 'model capabilities and require- 
ments such that model ,strengttvs andMimitat ions will be com- 
municated to decision makers and potential users. The 
Manager's Manual will -provide managers with sufficient in- 
formation . to 'permit them to. accurately 'assess model inputs 
requirements (including time, money, and \othcr resources), 
available outputs, and the accuracy and precision of the 
results. Managers can use the Manager's Manual iA justify- 
ing, the employment of the' model and in evaluating subsequent 
results. FiguTe' II-l is a recommended table of contents for 
preparing a Manager's Manual. The sections and subsections 
included in that f igure s 1 i s t * sugge s ted topics that are of 
erest to managers. Items-%ay be added to or deleted from 
this table of content 8 , Jbtpwever , according to individual re- 
quirements. 

lu Introduction 

The introduction should identify the sponsoring organi- 
zation, * provide the background of the project, state the 
purpose of the model, and present an overview of the remain- 
ing sections in the manual. A cofemon introduction used for 
othe r< manual s prepared for a model may be used only if that 
introduction is void of specialized terms. .The specific 
purpose of the Manager's Manual should be included' in the 
introduction in a statement of 'the form: 

"The purpose of this manual is to communicate to 
management the capabilities .and limitations of (model 
• , name ) • H 

* *-*_«_,,,„ 
2. Model Description ♦ ^ * 

<. » * 

This section should * provide a summary of model capabil- 
ities and limitations. Use high-level block diagrams to 
clarify the nar tat ive , Vs needed. 



1. Introduction . 

2. Model Description* 

2.1 Capabilities ~, 
-2.2 Input/Output Classes 
2 .3 .Assumptions* and* Limitations ' 

3. ' Model Development, and Experimentation 

3.1 Development history - 

3.2 Verification and Validation'* 

3.3 Model Experiments 

3.4 Costs and Resource Requirements 

* • * 

r 

4. Current and Additional Applications 

4.1 Current Use 

4.2 Additional Applications 

APPENDICES 

A. - Project- Documentation 

B. Bibliography 
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2.1 Capabilities'- m m / 

This subsection should briefly summarize the capabili- 
ties of the model* Include highlights of mathematical aftd 
engineering concepts (but nat equations) used as the basis 
of the model v Include a' statement of the model's primary, 
purpose* For example* "the model can be used to determine 
thre daily number of Machines in a job shop required , to pro- 
cess the % daily orilijrs.." Provide >an overview of "functional 
details that explains how the model accomplishes its stated 
purpose. . Discuss the general areas of ,the model's" applica- 
bility, including the decision making environments. For ex- 
ample, describe the types of .systems and situations 'that can 
be simulated J>y the model (possibly with minor chafnges), in- 
cluding the numbe^and ^inds of subsystems thpt can be simu- 
lated. Fpr exapple, v if a job-shop model includes e order pro- 
cessing, machine repair, <xr distribution subsystems ^ 'then 
theitr^descript ions should be provided. Also include the re- 
lationship of this model, to any other models (i.e., another 
model may prepare input /data for this model). 

-2.^2 Input/Output Classes 

Provide a short discussion on, the different classes of 
input data , required to drive the model and of output data 
generated* by the model.".- For example, a job shop model might 
require entering the numbet of production centers, the 
number of machines per production center, the service* rates 
of the machines, and the routing of the jobs ( order/) .^(Ex- 
amples* of model output include statistics that show the 
utilizations (percent busy time) of ,tjie production centers 
and the jab,, turnaround (total processing) timei. Identify 
any special preprocessing required for input [data, as well 
as aTl^past- proc|%sing required on model results. 

2 ; :J Assuto'p t ions and Limitations 

* * * ■» 

\. List assumptions and limitations concerning the appli- 
cability of-* the model. Identify any restrictions on model 
usage caused by accuracy limitations of input data and out- 
put . quant it ies Provide comitfei|ts on levels of detail it^ the 
model that affect the 'model*. s applicability. For* example, 
an analytical representation rather thkn a detailed simula- 
tion of a fcystem^componenfc could affect model application. 
Also describe 'any use of random parameters that may affect 
the accuracy and use t>f nio^del "output . 4 %' ^ 
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3. Model Development and Experimentation. 

» 

This section should describe significant model experi- 
ments %lready run and should provide details* on model ver.if- 

• ication and validation procedures usedN # Include information 
on tfe4 model's .development history resource costs and re- 
quirements; and use. 1 

3.1 Development History " 

\ This subsection shpt^ld provide pert^Jlent details of the 
history pf model development • Include comments on any air 
ternative methods to computer 'simulation that were con- 

• ffidered. provide inf orjpaat ion on any "lessons learned*' dur- 
ing model development, such as cost overruns, model* develops 
merit delays, user dissatisfaction with model results, insuff- 
icient workload data to support current and future model 
applications, inadequate model documentation, poorly defined 
problems, etc. 

* 3.2 Verification/Validation « 

f 

This subsection should describe any verification and 
validation procedures performed on the model. Include any 
analyses performed on the sensit ivitj^of model output data 

• to variations in model input data. 

1 3.3 Model Experiments ^ ' jf* 

Describe significant model experiments performed 'and 
their results. Briefly describe the purpose of each experi- 
ment and the extent to which each experiment's goals were 
realized* Discuss the management decisions affected by each 
experiment* Discussion of major model experiments may' be 
included in separate subsections* ^e .g . , 3 • 3 • 1 , ' 3 • 3 • 2 ) .. 

^ * - k 

* 3*4 Costs and Resource Requirements 

This section should provide details on the costs and 
resource requirements of the model. Include the cost (in 
^time and monej) of collecting and validating input data. 
For example, long and co-stly data collection efforts may be 
necessary. Provide comments on model maintenance and exper- 
iment costs. Discuss job "turnaround times (including typi- 
cal run times) and* peculiar model requirements such as ab- 
normally large core requirements or long run times. Include 
comments o'n model portability and security requirements, as 
needed. 



m 



9 

.ERJC 



-7- 



11 



4. Current, and Additional Applications- 

# • * A ' * * 

* * \ • 

This section should summarize benefits already derived 
ftom the ■ model and recommend other applications for the 
model, » , 

* s c * 

A. 1 Current Use * , 

* > * 

This subsection should briefly describe how the mddel 
has been used by management in'its decisionmaking process* 
Provide details of recommendations and conclusions derived 
using the models ♦ J 

• - ' . : 

4.2^ Additional Applications 

This subsection shoiild proyide details of any addition*- 
al applications and use's of the model beyond the current 
usage* Di scuss * in general terms any* extensions and enhance- 
ments . to thermodel which are feasible, a^id could improve its 
utility^ Identify any extensions which have been scheduled 
or planned \ " * 

' S ' %# - f 

APPENDICES . , { 

Two appendices should be provided as required* Appen- 
dix A should reference all ,other project documentation (in- 
cluding the User's .Manual, Analyst's Manual, and 
Programmer's Manual;), including references to the organizar 
tion and person 'responsible for maintaining the document. 
Include references to any documentation of experiments per- 
formed using the model* Appe l ndiTt B should list all applica- 
ble documents (excluding project documentation previously 
included in Appendix A)/* including cited and uncited refer- 
ences* < 
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This section presents Recommended User's Manual or- 
ganizational structure and discusses the consents of sec- 
tions and subsections to be included therein., A User's 
(Manual* prepared using these guidelines will enable a nonpro- 
gramming model user to understand the model's logical struc- 
ture, the input data requirements, the results produced by 
the model, and the use of model- results, .figure in-1 
presents a recommenced table of contents for a User's Manu- 
al* The sections and subsections contained in the figure 
cover the general needs of a user interested in a model. In 
documenting a particular model, however, sections and sub- 
sections may 'be added to improve clarify, and some subsec- 
tions may be omi ttecfc :f or, simple models. Note that' there' is 
a certain amount of- redundance amdng the various' sections of 
a User's Manual prepared according to these guidelines. 
Nevertheless, the progressively increasing level of*detail 
dictated by this structure is desirable to satisfy different 
levels of user interest; in the manual* 

1 Introduction "* 

The User's Manual introduction should contain the back- 
ground of the project, the purpose of the model, and an 
overview of the remaining lections in the manual. A common, 
introduction may be used for all the manuals prepared for a 
modoj., but, the specific purpose of the User's Manual should 
be included In a statement o^the form: 

"The purpose of this manual is to provide ftonp tog ram- 
ming- users of (model names) with the information neces- 
sary to use the model effectively." 

* 

2* Description of the Model 

This section should cdntain a veil-structured presenta- 
tion o£ the logical details of the model. The material here 
should be descriptive and include block diagrams and tables 
and r charts where needed; it should no*t give details needed 
by a data technician to run the model. 

2 . 1 Overview # / 

This subsection should provide sufficient general in- 
formation about the model to assist a user in determining 
the applicability of the model for specific need#. 
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' 2. Description of the Mc&el * - 
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2U Overview * ' 
2*1.1 Hodel Identification 
«• -2.1*2 Physical System Highlights 

2.1. 3 Model Applicability 

2.1.4 Inp^t.and Output 

2.2 Methodology > v 

* 2.2.1 "Physical System Details 
2*2 2 Modal Loaic and Data Flow 
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2.3 y Assumptions and Limitations 

2.3.1- System-Related Assumptions and Limitations 
2.3*2 *odel Parameters 

2.3.3 Output Limitations * 

2.3.4 Restrictions on Model Use 

3. Model, Input Data , 
3.1 General Description 
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* ' 3.2 Detailed Descriptions 

3.2.1 Data Set Name (First Data Set) 
3*2.1.1 Number of Inputs 
, 3.2.1.2 Other Related Data Sets 
3.2.1.3 Description of Data Items 
* • 3.2.1.4 Sample Input* 








3.3 Data Collection and Maintenance ' 
• 3*3.1 Data Sources 
3.3.2 Collection Procedures 
3.3*3 Oodatina Procedures 
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4. Model Output Data 
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4.1 General Description ^ 






• 


» 

4.2 * Detailed Description 

4.2.1 Data Set Name (First Data Set) 

4.2.1.1 Description of Items 

4.2.1.2 Interpretation 

4.2.1.3 "Sample Output . 
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5. Run Preparation Instructions 
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5.1 Run-Stream Description . 

$.2 Resource Requirements 

c 3 r*c tart /Recovery Procedures 








6. Sample Model Run 

7. Trouble* shoot inc Guide 
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2 ; 1 .1 Model Identification The identification should contain 
the name of. the physical system being simulated^ nanvfe of the 
model (acronym and expansion), programming language(s) ,us,ed 
tot implement, the model, computer(s) on which the model may' 
be run, and relationships, if an#, to other model.s • f * 

2.1..2 Physical System Highlights * Include a block diagram 
that shows the physical system or phenomenon b^ing simulat- 
ed. Discuss, at a macro leyel, the major system elements 
shown itb the diagram, their relation to each other, and ,t"he 
flow of control information, dat#>, and activity between 
them, as appropriate. In the case of complex models, pro- 
vide in this subsection a first-level block diagram that 
shows the major subsystems and their interactions, and post- 
pone the details of each of the subsystems until Subsection 
2;2.1. iFigure, III-2 is an example of physical system 
highlights depicting the operations of a typical shop mofiel. 

2.1.3 Model Applicability Discuss the general**magnitude of 
model applicability. The types of systems or situations 
that can be simulated by the model (possibly with minor 
changes) and the number of subsystems (e.g., production 
centers and machines per production center in a job shojj 
simulation) that can be handled are examples of material to 
be included in this subsection. 

2.1.4 Input and Output . Provide a general statement of the 
different kinds of input data needed to drive the model, the 
t>utput data generated Jby the model, and" uses of model *out- 
put. FQr example, a' job shop model v might require entering 
the number of production centers, the number of machines per 
production center, the .service rates of the machines, and 
the routing of the jobs (orders). Examples' of mod^el output* 
include statistics that show «the utilisations (percent busy 
time) of the production centers and the job turnaround (to- 
taf prpcessing) times. Jhe principal model user could be to 
determine the number of machines in a job shop required to 
process the da,ily orders. ^ ^ # 

Highlight any special data collection procedures (e.g., 
run other modelscor computer programs, extract data from do- 
cuments o* li stings ,* conduct sampling experiments) required 
to produce model input data. Lijst any unique data sources 
or other organizations that might have to be contacted to 
gather data. Figure III-3 is an example of an input/output 
'schematic. 
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2.2* Methodology # ♦ 

v * ; • ^ 1 1 " r . 

This subsection should provide the *user with a detailed 

understanding of* how th& model works. 

> - 

2.2.1 Physical System Pet-ails . This subsection^ is .an . ela- 
boration of Subsection 2.1.2. The operations that take 
place In each of the bl-ocHcs in the Physical 4 System Block Di- 
agram shISuTd be - discussecf* in detail. Detailed black di- 
agrams'of subsystems should be provided fox* a complex, model. 
The level of detail used in the simulation (e.g., the 
smallest meaningful time increment for % event- type models , 
the way in which- complex system interactions are % simjM if ied 
itt^the model) should be clearly indicated/ 

2.2. 2\ Model Logic and Data Flow . Thi^s subsection, should 
describe t the logical fTow of* data throughr'the model, from 
the entry of inp'ut" data to the generation of *oytput data. 
Include a schematic that indicates the ma jo£ -'model software 
elements, the data flow between model elements, • and model' 
inputs and- outputs. Figures III-4* and 111^-5 are <two typW^. 
of schematics for* the *same^ model. Edther 'of these 7tw r o 
types, or any other type of schematic t^hat cle'arLy de,pr>f'ts 
model logic and data floW, may be used. Accompanying dis- 
'cussion should relat'e model elements and 6 data flow to physi- 
cal syst'em elements and data flow described in Section 
2.1.2." For complex models, include a table ^that relates 
physical system names to the program, segments that simulate 
them. „ . ' % 

2.3 Assumptions and Limitations' * • ^ » 

All .the system-related assumptions., assumptions on 
mode 1 « parame ters (e.g., hard -coded values), limitations on 
output accuracy, and. any restrictions, on the us6 1- of tTie 
model should be d iscussed ~im detail. 

2.3.1 System - Related Assumptions and Limitations * List ' *any 
assumptions that* . limit or describe the kinds 4 of systems or 
phenomena thatare treated in the .model. For examplte, a 
description of a j^b, tett<>fc modeiPsKbuld define the\ model's 
boundaries (i.e., the^jsub^y stems that the* model includes), 
the kinds of activi<ti€Ts Simula V^d (e .g . /machine failures 
and repairs), etc. 



\ 2.3.2 Model Parameters . tist the valid ranges for principal 
^ model inptft ^parameters (e.g. , the maximuim and minimum 
number of subsystems) • Also list values for 4 arty * parame.te^rs 
that are included 15 in the model .software and* cannot 0 be modi* 
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2.3>3 Output Limitations . List any limitations on routput 
usage caused by inaccuracy of the output data. For example, 
all digits in an output data 'field may ,not be significant 
because the input data are estimates, and high precision in 
theOutput data is either unobtainable or inappropriate. -\ 

Restrictions on Model Use . .Enumerate all ^restrictions 
on mode4 usage. For example, a .job shop 'mo*Jel restriction 
might be that only first-in, first-out queuing ™d/isc ipl ines 
are modeled for the production canters. ' * <- 

. > \ t <\ 

'3.' Hodel Input Data 



This section should describe in detail all the input 
da.ta needed to run the"model. The material in this and the 
four subsequent sections should serve as a reference for 
both the u-ser and the data technician who runs the model. 

* t 

3.1 General Description • , - . 

This subsection should describe the ovefall input data 
structure and the data media (tape, cards, "disk data sets, 
etc*). Include a^ table that shows input data set names, 
the!* media, - and any general data limitations. Also, 
describe the interdependence, if any, of .input data sets. 
(Detaiie<d descriptions' of individual data- items within the < 
input <iata sets should be left for Section 3.2.) 

3.2 Detailed Descriptions 

Inptfrt data* itei»s are normally organized- in related 
groups, such as machine performance characterises , job 
processing requirements, etc., or as the- data items that are 
entered^on one punch card. These related groups of-data es- 
• tabl^tsh and define a data .set and should be described, to-, 
gether. The input data sets and the items within each data 
set should be discussed ii\ 7 the order of their appearance in' 
the run stream. For Ceach input data set,, p»t>vide the fol- 
lowing infarmation (eactr.fya set description , should begin 
on a new page). 

3^2.1 Data Set Name. 



con- 



In this subsection, give an overview of the data set's 
tents and its purpose./ / _ . ^ y 

3.2.1.1 Number of Inputs . Indicate the number of d"a'ta sets 
of this, type and the maximum number of data items in the 
data set that may ( or m ust) be use ^ in the simu latio n. Di s- 



cuss any factors that influence the total number of inputs 
from this data^set 



3#2 \ 1% .? Other Related Data Se ts . List any data frets whose 
content* depend on at dictate the input values for this data 
set,* Discuss the relationships between data items in the 
data set 8. *\ v ^ * 

3.2.1.3 Description of Data Items * » In this subsection, pro- 
vide general comments d,n the format of the Aa-ta items (e.g., 
free. form,, integer in qard -columns 8-1 1 -NAMELIST ) followed 
by the description oi, each of the data. item^. For each 
itejr, the following should be given: name, type, format (if 
fixed),, permissible rajtge or fixed value , unit of measure- 
ment, Idefault value (value assumed by the program when the 
item Jis omitted), definition of the item describing how it 
is used in the model, relationship to other data it^ms. 
Table 8 should be used* where appropriate • 

3.2.1. 4 Sample Itiput . I, - # ^ 

v i '• J 

A format layout should brf provided for the data set to pro- 
vide, the user a visi/al reference for preparing the input 
data. 



4 



3.3 Data Collection a s nd Maintenance ^ 

* * * * 

An important part of model application is data, collec- 
tion. Therefore, it is necessary to'include appropriate in- 
structions on data collection and maintenance. ^Specific 
responsibilities need to be assigned to analyst-s apd users 
for these functions. 

3.3..1 Data Sources . Discuss the data sources for each input 
data set. The discussion should identify the form in which 
raw data are "available, other organizational o elements from 
which the data must be col lec ted f~i f appropriate^ and the 
time required to collect'&the data. 

3*3.2 Collection Procedures . I>escribe any 'special statisti- 
cal t^chniqiie^j/or experiments cor obtaining the data. * Iden- 
tify ajjy, other computer programs or models, that must -b^ used 
to cortect or process data; and list or reference* instruc- 
tions for their use. Where appropriate, include a flowchart 
that illustrates' the major data collection steps and their 
sequence. Pfgure III-6 is an example of special procedures 
to be used in obtaining dtfta fojr a model. In .this example, 
the type and frequency of orders are analyzed alorig. T with 
production center performance data to produce a stat 1st ical 
data ba^se. This 'data base^Jj^^then^Gsed as input to a mod,el 
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of the order handling process-. The order model produces 
data that profiles the arrival patterns, routing distribu- 
tions, and processing requirements of the jobs. These data 
are,, in turn, used as input to the job shop model. \ 

3.3.3 Updating Procedures . Give step-by-step procedures for 
maintaining the data sets and preparing them for new experi- 
ments. Identify any other computer programs .that*, must be 
used to update (the data se,ts, and' list or reference instruc- 
tions for their- use. Where appropriate, include a flowchart 
that illustrates the major* update procedures and their se- 
quence* * 



Model Output Data 



This section should describe in detail all the output 
data pVoduced by t.he model and should indicate their mean- 
ings and uses, v * 

i&l General Description 

Discuss the overall output gtruct/ure in this, section. 
Indicate the number and types of output data sets, -output 
media, correlation between outputs, quantity of output (op- 
tional and mandatory), and postprocessing, if any, that 
should k«L per f ormed on the output data. 




4.2 Detailed Description 



For each output data set (or major groupof .logically con- 
nected data items), provide \ther fojtjrowing* Information (each 
output data, set' should begin ytt a new page). 



A.2rl Para Se t Name . Give the fuU' name or acronym ■ of the 
output data set or group of data under this Subheading, 
Give an overview of the data set's contents, its purpose, 
and. its relation to other model Results. < 



t4.2. 1. U Description of Items . Each output item* should be 
included, in ^a table that shows its name, a brief descrip- 
^ion^and gives information to use in validity checking, if 
appropriate* Accompanying discussion should expand on each 
* .MjfT? <* e 8crlption .and should show Jh^ow the ite4s are derived 
or calculated. Include mathematical * formulae where ap- 
propriate. .* •* 

4.2.1.2 Interpretation . Explain how the data Jr-tems can be 
used, and. describe actions to be taken for any subsequent 
runs based on the output. 



4.2.1.3' Sample Ou t put . Include a sample of the output data 
set. ' A* sample format la satisfactory where it is not prac- 
tical to provide an actual sample. 

■ * V • | 

~5~. Run Preparation Instructions » * 

:/This section' of the User's Manual should -describe pro- 
cedures for organizing the input data to submit computer 
r^ns as discussed in Section 3* 

"* , * 

5.1 Run-Stream Description |* 

This subsection should gj.ve a pictorial (or tabular) 
representation* *of the deck constituting the run-stream that 
shows all the control cards and the data cards in proper se- 
quence. Mandatory and optional cards/ should he discussed. 
If the model is interactive, include comments on any special 
techniques used for interactive submission of jobs. 

5.2 Resource Requirements ^ 

This subsection should describe the computer resourced 
required by the model. These include main memory, mas** 
storage, number of tape units, execution time, numbers of 
punched xrards, and printed lines expected as output. If the 
computer resources vary depending on input data, provide 
aids to estimate them. 

5.3 .Restart/Recovery Proceduqes/^ 

For models that require \ large amounts of computer 
resources it is important to frAcover from abnormal termina- 
tions and to restart the job. II any such provisions are 
made in the model design, they should be discussed in this 
subse ctibn. . ^ 

6. Sample Model Run 

Include a sample sun that Illustrates the complete In- 
put scenario and the resulting output to assist a beginning 
user in making a test run and verifying correctness of pro- 
cedures. 



7. Troubleshooting Guide ! > 

'Tabulate user input error-messages prodtffced 'by the 
JO del .software , and describe the required corrective action . 
**Since other errors should be handled by — programmers, -chose 
errors should -be discussed in the programmer's manual* 



APPENDICES 

Three appendices should be provided as ^required. Ap- 
pendix A should provide an alphabetic-al listing of all ab- 
breviations and acronyms used in -the User's Manual. Appen- 
dix B * should list -all specialized User's Manual terms and 
their definitions; All applicable documents, including cit- 
ed and uricited referenc.es, should be provided in Appendix C. 
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IV. GUIDELINES FOR PREPARING A PROGRAMMER'S MANUAL 



This section provides a re commended^ organi za tion for a 
Programmer's Manual and describes the ^contents of e;ach seTc- 

tio n and subsecllua p r o p &sed fr&* t+ha-fc m a nual . — - — A 

Programmer's. Manual written using these guidelines will en- 
able a prdgrammer to maintain and modify a model. , The 
guidelines "will provide all Che details necessary for a .pro- 
grammer to understand the operation of the model and to 
trace through, it for debug-ging, for making modification's, 
and for determining if and tyw the model can be converted to 
other computex^&ystems . Figure IV-1 is a recommended table 
of contents for a Programmer's Manual. The sections and 
subsections included in tfhe figure cover the general needs 
of a programme r interested in a* model. In documenting a 
particular model, however, sections and subsections may be - 
adMed to improve clarity > and some subsections may be ^ omit- % 
ted for simple models. Any appropriate documentation pro- 
duced using a program documentation language could be used 5 
to satisfy the guidelines contained tierefcn. 

1. Introduction 

The introduction to the 'Programmer' s Manual should con- 
tain thei background of the project, the purpose of the 
model, and an overview of the remaining* sections in the 
manual. A common introduction may be used for all the manu- 
als prepared for a model, but the specific purpose of a 
Programmer's Manual should be included in a statement of the 
form: ' " 

"The purpose of this manualeis to provide programmer 
personnel of (model name) with the information neces- 
sary to effectively maintain and modify the model." 

2. Model Specifications 

This section should provide a summary of the model's 
specifications, including ^capabilities (i.e., problems ad- 
dressed' and methods of solution), a" de script ion of the host 
computer system, and 'the processing requirements (i.e., 
.memory, peripherals, languages) placed by the model on that 
host system. The details; should be presented in tabular 
form (supplemented by narrative description,* as appropri- 
ate) J Whereby ot\e table describes the .complete modeling sys- 
tem and additional tables describe major submodels or pro- 
grams 4s needed for clarity. 
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3. Model Description 

3.1 ^Processing m 

3.1.1 Overview 

3.1.2 Major Components .Jpf 

3.1.3 'Model Initialization and Wrap-up 

3.2 Data Structures \ 
3.2.1 Local Data Structures 

\ 3.2.2 Global Data Structures 
t . 3.2.3 Special Data Structures 

3.3 Overlays t 

3.4 Model Modifications « • 

3.4.1 Planned Maintenance 

3.4.2 Other Changes _ 

4. Description of Routines 

4.1 Routine Name (First Routine) ' 

4.1.1 Purpose 

4.1.2 Type 

4.1.3 Calling Sequence 

4.1.4 Argument Definition 

4.1.5 Calling Routines, 

4.1.6 Called Routines 

4.1.7 Piles 

4.1.8 Error Messages 

4.1.9 Narrative 

4.1.10 Block Diagrams 

" 4.1.11 Sample Test Run 

5. Data Base Description 

5.1 File' Name -(First Vile) 

5.1.1 Purpose 

5.1.2 Format 

5.1.3 Routines 

5.1.4 Updating . 

6. Source Listing * 
J % ^J^ror; Messages 
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3* Model Description « * 

Thii section should contain a well-structured presenta- 
tion with emphasis on the operational details of the model. 
The fria c ussioiu s hotrih l be written — Ui — *n e asy-t o-un d er s 'tand — 
manner that cross-references special model language terms 
with modeled system features whenever possible. This sec- 
tion should be, divided into fou^r subsections. 

3.1 Processing 

This subsection should provide details on model opera- 
tions \for programmers who need to understand the processing 
techni^Jjfcs used in the 'model. The discussion shouJjC be at 
the Macro level, with a discussion of internal routine de- 
tails postponed until Section 4 of this manual. Details on 
I/O foifmakts and^default input data values should be reserved 
for the tier's Manual.. Blpck diagrams should be used as 
necessary to^ supplement the narrative. > 

3.1.1 Overview . This subsection should present ,* in modeled 
system terminology, an dverview of the problem solved by the 
model. Include a discussion of the basic tasks modeled. 
Figure IV-2 is an example of a bloc*k diagram that could sup- 
piemen-^ a narrative description in^this Subsection. 

3.1.2 Major Components . Th is . subsect ion should describe the 
flow of data or control information thrdugh the model at the 
major routine, or routine group, level. Include detailed 

•block diagram^ that depict paths among the modeled tasks, 

highlighting major decision points in the logic flow. This 

subsection 1 may contain as many levels of discussion as are 
necessary to clearly describe model operation| 

3.1.3 Model Initialization £nd Wrap-Up . • This subsection 
should note any differences in the performance of model 
tasks accomplished during model initialization and w^a^up 
and those same tasks when performed during normal process- 
ing. ■ % v • * 

3.2 Data Structured . * 

This subsection should provide information on all data 
structures internal to the model. Include, descriptions of 
local and global variables, arrays, and da£a sets, as well 
£$ any special data structutes^ such as the set-entity rela- 
tionships in .SIMSCRIPT. If required for understanding, 
separate descriptions of each array index should be provid- 
ed. r • 
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3.2».l Local Data Structures . Thip subsection shou-ld contain 
the meaning and purpose ST. all local variables; artays, and • 
4 data sets (local data structures have their values defined 
only within particular routines). To improve clarity, loca^V 

— ~nchara ^rr^nrrur e^ s h cniri^^1re~^ffvoxinate^^r!rth-- tire — rtnrtimes — in 

which they appear* _ 



3.2.2 Global ^ Pata Structures . ~TRis subsection should con- 
tain the meaning and .purpose of all global variables, ar- 
rays', and data sets (global data structures are defined 
throughout the model). Include an alphabetized list of glo— 
bal data structures '(including special data structures), 
crossrref erenced . by the routines in which they appear, and 
the source code line ndm'bers (Table IV-1). Source, code linfe 
numbers can be obtained, from the source listing in Section 6 
of this manual. Examples of , global data structures that 
should be included in this subsection are the COMMON, blocks 
* of FORTRAN. 

JlZ2'.3 Special Data Structures . Any special data structures, 
both local and global, should be listed and described in 
this subsection. For'example, a job shop model implemented 
in .SIMSCRIPT might represent the jobs with temporary enti- 
ties, the job processing requirements with entity attri- 
butes, and the sequence of production centers required to 
process the job with" a set (owned, by the job with production 
centers as numbers). A GPSS implementation, however,' might 
represent th* jobs with transactions, the processing re- 
quirements with transaction parameters, and the route with a 
row in a matrix save value (the columns contain the sequence 
of production* centers) . * 

3.3 Overlays * * 

If the model is overlayed, thi* 1 subsection should pro- 
vide details of the overlay design decisions that determined 
the overlay strategy. ^ Included should be a narrative and a 
blc/ck diagram description of the control -flow of the over- 
lays and their interactions. Figure IV-3^cont,ains a sample, 
overlay structure with a main program, four primary overlap, 
segments, and five secondary overlay segments. Routines 
. residing i.n each overlay, and their memory « requirement s , 
\ should be listed (Table IV-2). References should be madfe 
to the- discussion ;of model processing in this manual (Sub- 
section 3.1) to reinforce or clarify the overlay discussion. 
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— NUMBER" 



NAME 



TTEM" 



"RDOTlNr 



SODRC E CODE 
"LINE NUMBER 



AM GO (V): 
AOPS (A)' 
BVBC (V) 



CMCODE-. (V )' 



MAIN 
FASTER 
MAIN .-• 
TPBAI 
PRNTREP . 

* 

M^IN \ 

AtiSUMT 

PRNTREP 



LEVDAT (DS)" 5 MAIN 

AUXSUM ~ 
T.HBftB ' 
THBAI • , 
PRNTREP 

TCTV (V) MAIN 

ABESTR"" - 



PRNTREP 



Item* is a variable. 

2 

Item is' an array. 
^Iterii is^V data set. 



'# 



.15,- 
52^ 

163 
240 
212 
290. . 
*10 
150 • 
211 . 
286 
13 
120 
184 

195-^ " 
^250 
14 

106.' e 
108. 
210 
253 ■> 



CRQSS.-REFERENCED DATA STRUCTURE LIST SAMPLE 

TABLE IV-I ' *" 






• * 


w * 


■i * 




* * 


1 i 

x 

l * ' f - 








" * 






-v. •* 


• 










1 

4 








MAIN OVERLAY , 

"> .' ■ /-\ • .: 


-> 








* ' J * . 














b ■ . 














/, / 




* < 


» 




e 




t 








(1) 






13) 


a » 

• 






* 












J*' 


* 








• 










(7) 


(8) 


(9) 




(5) . 


(6.) 

• 




V 


* • ' ♦* * 






















* » 






■ 


» 


i 

tr 
e 




9 

* 



SAMPLE OVERLAY STRU<£TURE DIAGRAM j 

FIGURE IV-3 ; • " ■ 




OVERLAP — 

SEGMENT NUMBER 



3 

4- 
5 



6 
7 

8 
9 
10 



" ROUTINE " 
NAME 



MEMORY-- 
REQ U IREMENTS 



MAIN 
ROUT1 
ROUT 2 
•ROUT 3 
PROC1 
PROC2 
PROC3 
" COMP1 
'COMP2 
SOLVl 
SOLV2 
LSIGN1 
LSI6N2 
LSIGN3 
COMP10 
FlNDl 
FIND2 
SUM10 
WRITER 
REPORT 



(KBYTES) 



50 

10 

20 

20 
100 

25 

25 

75 

50 

75 

50 
100 
« 20 . 

15 
140 . 

P ™ / 
48/ 

• 140/ 

137/ 

128 



S'AMPLE LIST- OF ROUTINES' BY OVERLAY SEGMENT < 
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3.4 Model Modifications 



This subset: t i&n should include inf or mat ion Concerning 
changes in model .software and data ba^s. Include a 



dsscr ipt ion- of — any p r ogramming conven t ions use d — in^ the mod,e 1 - 
(e.g., all variables referencing one* data b&se may begin 
with a specific character). In' addition, this subsection 
should provide procedures needed by programmers during the 
mode 1 compi lat ion , recompilation,and execution stages. I n- 
clude a sample control card setup' that illustrates each of 
those states, including mandatory and optional cards. 1 If 
the model is interactive, include comments on interactive 
procedures. ' * f 

\ ( 

3.4.1 Planned Ma intenance . This subsection should * identify* 
all planned periodic, maintenance on the model and its data 
bases (e.gi, periodic data base updates). , * 

. <;«< * ~ 

3.4.2 Q^ther Changes ♦ This subsection should identify pro- 
cedures fo„r>aking a 1 l^nod i f ic a t ions to the model other than 
planned periodic maLxiteinance . Provide > details for making 
changes necessitated, ay programming errors discovered during 
model usage, as well as changes t-o^ the model required by 
changes in the host modeling language. Include directions 
for implementing Software changes ,to produce a new version 
of the model (e.g., changes in model applicability). 

4. Description of Routines 

Thi-s section should* provide a .detailed* description of 
principal mode.l routines. Include a discussion of all types 
of* routines that comprise the model ^ (i.e., event, 
subroutine, function, etc). Provide an alphabetized listing 
of all routine names along with calling routines and called 
routines (Table IV-3) or a block diagr^a^n showing routine 
linkages, as weeded. Each routine should be described in a 
separate subsection. For each routine, provide the follow- 
ing information. * \ 

4.1 Routine Name (First Routine)^ ' t 

4.1.1 Purpose . Briefly state the purpose of the routine 
(e.g., routine ALLOCATE computes the time a- jiob i& scheduled 
to complete its processing at aproduction center). 

4.1*2 Type ♦ Specify the type of routine ( i .\e . , function, 
Subroutine). A description of all routing types in the 
model should be contained' in v the introductory^ comments o'f 
this section. ' 




1** 



A. 1.3 s Calling Sequence . List ^all variable*, arrays 
pointers in the routine calling ^equetrce. 

4.1.4 Argument Definition. Define all routine arguments^. 

A. 1.5 Calling 7 Routine s . List all rQrttine^ that call this 
routine. ' " » 

4.1.6 Called Routines , List all routines called by this 
routine • • 

4.1.7 F^iles . List all files this routine creates or uses. 

4.1.8 Errox Messages . Itemize all .error messages which c^an 
originate in this routine. " 

4. ^1.9 Narrati ve . Include a narrative description as neces- 
sary, to amplify ,and highlight subtleties included in the 
code • As a' minimum , include any equations and * formulae 
referenced ^froln the Analyst's Manual. - 

4.1.10 Block Diagrams . Use block diagrams <h: other documen- 
tation aids (such as program documentation languages), as 
required, to clearly depict operation of the routine. 

4.1. Ib jftample Te st Run . Provide the results of test runs, 
along with, values .oPTnput darta, for each complex routine to 
assist in verifying changes to those routines. 

5. Data Ba se ~De script ion - * 

This section should discuss all mass storage files used \ 
or created by the model. Each k f ile should be described in a 
separate subsection and should contain the following infor- 
mation (each file description should begin on a new page). 

5.1 File Name (first File) ^ 

Provide the full name or acronym of all tt\e model 
files. \ . 

5.1:1 Purpose . Briefly state the purpose of the file (e.g., 

contains preprocessed destination data). 

5.1.2 Format . Explai'n the format of the file '(i.e., blook,' 

size, record size, data item ident if icat ion , ' and field 
sizes). 
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i NUMBER 



it — - r 

CALLING ROUTINE 



CALLED ROUTINE 



1 4 


ABFSTR 


2 


. . Acsurac 1 


• 

3 


AUXSUM 


4 


. Faster 


5 , 


.MAIN 


6 ' ' 


PRNTREP 


~ 7 


TPBAI 


' 8 


THBAB 


9 


THBAJ 



NONE 

TFBAI 

THBAB' 

ACSUMT 

ABPSTR 

AUXSUM 

t FASTER 
NONE 
PRNTREP 
THBAI ' 

•^RNTREP 



CROSS-REFERENCED- ROUTINE LIST EXAMPLE 
TABLE IV-3 ' 
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/ * • , \ 

5.1.3 Routines . Identify all routines that — use or create 
the rile. « ' / O 

*/ 

5.1.4 Updating . Include Instructions f^r file maintenance 
and updating as appropriate. 

6. ; Source Listing f ^ w 

This section, should contain the source code of the 
model. If the source, listing ls( large. It should be bound v 
separately and made available upon request. Also, source 
listings with line numbers can be referenced from Subsection 
3.2.2 as a cross-reference for model variables. 

, f ' ' : • (' 

7. Error Messages 

* 

All, program-generated error messages,, the names of the 
routines* in which they are generated, and suggested correc- 
tive actioms should be lifted in this section. Each error 
message may be described in a separate subsection.. 

• 4 

APPENDICES ^ 

\ " Four w appendices to - this manual should be provided as* 
'required. Appendix A should define all terms in the 
Programmer Manual not defined elsewhere in the document. 
A list of applicable documents, including cited and uncited 
preferences, should be, provided in Appendix B. Appendix C 
should provide an alphabetized index that gives the 4 page op 
which each' subject contained in-the Programmer's Manual may 
be found; If the Programmer's Manual is "divided into more 
than 9 one volume, the index 'in the first volume should.be the 
index of the volumes. The^index in each of the remaining 
volumes should referenpe only* those subjects within that 
volume. 'Appendix *D should provide a listing of model test 
results along with "values entered into the model that * pro- 
duced those results. Include any interim model outputs 
necessary to understand the final outputs. Provide analyses 
of model results as necessary. 



V. GUIDELINES FOR PREPARING AN ANALYST'S MANUAL 

This section presents a recommended organisation for an 
Analyst's Manual and describes the contents of each section 
and subsection to be included in that manual. An Analyst's 
Manual prepared using these guidelines will enable an 
analyst to understand a model's functional structure, the 
algorithms used in the model, and techniques employed for 
model verification and validation. Figure V-l contains a 
recommended table of contents for an Analyst's Manual* The 
sections and subsections included cover th'e general needs of 
an analyst interested in a model* In documenting a particu- 
lar model, however, sections aid subsections may be added to 
improve clarity, and some subsections may be omitted for 
simple models* / 

1. Introduction 

The introduction ttf the Analyst's Manual should contain 
the background of the project, the purpose of the model, and 
an overview of the remaining lections in the manual* A com- 
mon introduction may h4 used for all the manuals prepared 
for a model, but the &p4cific purpose of the Analyst's Manu- 
al should be included In a statement of the form: 

"The purpose of this manual is to providfe nonprogram- 
ming analysts of (model name) with the aetails of the 
algorithms used in the model and the techniques em* 
ployed for model verification and validation*" 

2* Functional Description of the Model 

This section should contain a well-structured presenta- 
tion with emphasis on the functional details of the model. 
The discussion should be written in an easy-to-understand 
manner that, whenever possible, avoids the free of highly 
specialized terms* The section should be divided into four 
subsections* 

* 

2*1 Overview u 

This subsection should provide a functional description 
of (he model in sufficient det&Ll for £n analyst to under- 
stand, tbe salient system features that were modeled* Func- 
.^tibnal flow charts and other • graphics should be used to 
enhance the narrative*. . Include a statement of the kind of 
model (i.e., discrete-event model t^iat simulates jobs enter- 
ing a job shop at arbitrary points In time, being routed 
through a predetermined sequence of production centers, and 
being processed at the production -centers) and the degree to 
which the model portrays the* real world system* Figure V-2 
is an example df modeled system highlights*. Included should 

« V 4 
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modeled system' highlight's example .. 

figure v-*2 x 
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be the set of model responses (output) produced by a givejn 
set of mode.l input"*data. Figure V-3 provides an example of 
the types of model input and output. For additional details 
on model description, the analyst should be directed to the 
appropriate sectio^ of the User's Manual for this model. 

2.2 Detailed Methodology 

% This subsection should provide the functional details 
for analysts to understand the algorithms and equations used 
in the model. Well-known ' mathematical "equations (and formu- 
lae) should be clearly identified and references should be 
cited for their derivation. For example, in a job shop model 
the queuing d i s cTpTfne s i m u rwt e d f o r~~e a c h production center 
should be stated. Include the derivation for extensions of 
known results or for the development of new analytical tech- 
niques.* Special complicating details, such as the use of 
precalculated data for job arrival times sWuld be stated. 
The description must be detailed enough to demonstrate how 
the model uses the input data to calculate output informa- 
tion.- Functional flow charts and graphs should be used to 
enhance the narrative descriptions of each algorithm. Fig- 
ure V-4 is an example of a model fuactional flow chart. 
This sectioti should include a subsection for each major al- 
gorithmor set of equations. 

2.3 Assumptions And Limitations 

* This subsection should list all model assumptions and 
all factors that afX^JLI-^ij^ Th . e fol ~ 

lowing items should be inclucTQ) a* appropriate N " 

2.3.1 Stochastic Assumptions ., In this subsection, itemize 
all stochastic assumptions that affect model output accura- 
cy. For example, the * treatment of certain random varia&les 
in a simplistic manner, by using only their mean values and 
not sampl4ng from a statistical distribution, 'should be 
described in this subsection. Each stochastic -item should 
beJ^ described in a* separate subsection (e.g., 2.3.1.1, 
2.3.1.2). ♦ # ^ 

2.3.2 Magnitude Limitation s' this subsection should include 
all limitations on the size^of the problems the model can 
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address. Fo* example, the current dimensions of certain ar- 
rays in a model say limit the number of activities that can 
be represented in that model. Each limitation should be 
described in a separate subsection* 

2*3*3 Critical Values * , This subsection -should identify 
critical input data values to which model outputs are sensl-* 
tive. Many elements tKat have a range of values will have 
one value that is particularly significant to the analyst* 
This may be a-breakpoint , a minimum stock level, or a criti- 
cal job rate, etc*. Each critical value should be described 
in a separate subsection (e.g., 2.3. 3.1, 2.3.3.2, etc.). 

2.4 Model Flexibility _ * 

» 

This dubsection should address the capability of adapt- * 
ing the model tq changing requirements, such as an tici pated* . 
physical system operational changes, int e rap tirtfg with new or 
improved models, and planned periodic changes. An example 
of a flexible design is one that facilitates the addition of 
a machine failure and repair subsystem to a job shop model. 
Model components and procedures designed to be flexible • 
shall be clearly identified. Factors that affect mpdpj 
flexibility are the familiarity of' the analyst with the 
model, the model's size , its complexity, and its data, struc- 
tures. Subsections should be used as required. ' ■ fc •„ • 

3. - Model Input and Output Data # 

This section should discuss w the categories of i'nput* 
data an£ the accuracy of model output data. The material 
contained in the next two subsections will enable the 
analyst to assure the existence of the dat^necessary to Ex- 
ecute the model and to ascertain the accuracy of the data 
generated by the model. 

3.1 Input Data , s 

Identify all categories of ifiput data and an)y special •* 
analytical techniques required to obtain those datla. If the 
sources of input data include output* from other models, pro- * 
yide sufficient details to enable a? analyst po assess t*e % 
appropriateness of those data in solving his problem. * For 4 
exampler-^lf the arrival rate, of jobs is provided by a* 
separate model of the order handling, proces.s, the analyst, 
needs to determine that the simulated ordering process . 
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corresponds to the one existing t in his job. shop. Details on 
'input data/types k and * formats , phould be reserved far__ the*— 
User's Manual. * v 

3:2 ; Outjtut^Dat a » ^ 

""This subsection should provide the analyst with a^ 
metHodology for assessing the' accuracy of model output data. 
Since the accurate of the output values will bf /judged in 
relating to the -method used to derive *them, a review ,pf^the 
algorithms used t6 compute those output values m^y be neces- 
sary at this point. Describe in detail any corrective ac- 
tions to be taken by an analyst in case of inaccurate- output 
values, (i.e., Should the analys t _contac t a programmer for a 
program change or have a uder modify the inp,ut data d^ck , to 
correct the problem?). Subsections may be used as* required. 

4. Model Verification and Validation , . % 

This section of the Analyst's Manual should describe 
the methodology used to verify and . validate the model^ 
Model verification ( somet imes l%||prrfed to as software vali- 
dation) is concerned with the compa tibility of the model's 
programmed st^uct^ure to the analyst ' s design and with ^ model 
debugging. Model validation provides the analyst*, and user, 
with the confidence that the model provide-^ a good' represen- 
tation of the modeled system. 

4.1 Verification Techniques 

This section should provide an analyst with concise 
procedures by which the model was verified. Each equation 
included in Section 2.2 of .the Analyst's Manual should be 
verified and cross-referenced to the Programmer's Manual for 
this model. Include all other r veri f ic*t ion technique s used ♦ 

4.2 Validation Considerations ^ 

This section should, provide an analyst with the 
description of any procedures tkat were ttsed to ensure that 
the model is an "accurate" abstraction of the real system. 
Any methodology iised to detetmine how well 4 the model 
represents the reAl system shpuld be presented in this sec- 
tion, viliile complete 'conf idence in a model may be" impossi- 
ble, a, good validation procedure can increase the amount of 
confidence an analyst has in a modtl. Figure V-5 is an ex- 
ample of a graph that could be usea in a model validation 
procedure. 



APPENDICES 



Two appendices to thi» manual should^ be provided £t „ re- 
quired. Appendix A, should define ell term* In the Analyst's 
Manual not defined elsewhere in the document. Appendix P 
should provide a list of applicable' documents and a bibliog- 
raphy designed for use by system analysts* 1 
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• VI. MODEL SUMMARY 

It is suggested that documentation, fbr each , model in- 
clude the information outlined below, as part of the model 
documentation package. This information provides general- in- 
formation about the model and facilitates its possible use 
by others. ...... t 

A. Basic Description. 

1. Name or Hkle of M6del. 

2. Developer(s) • 

3. Agency or company. 

* 4. Sponsor; purpose or objective of sponsor. 
5. When developed? 
6*. Where developed? 
• 7. Development time and cost? 
_ 8. Developed separately or as part of larger 

study? 

8. Subject Matter of Model. 

1 . Ma j or purpose of model . 

2. Scope of model. 

3. State basic description or theory underlying 
the model* 

* 4.* State specific di«c ipl ine \ s ) required for model 

use , if required . 
* 5. How does mo^el differ from other similar 
models? | 

7 « 

C, Modeling Technique. 1 

1. « Describe type oL, model. 

2. Does model use any standard packages (e.g. 
linear programming, statistical, ejtc.)?- 

3. Was the model developed from another model? 
If yes, describe process. 

4. Is its structure clear? I.ts varJUbles?^ 

5. Describe data requirements pf model • 

6. Does model receive any data from other models? 

7. What constraints are affecting the model? 

D. Computer Aspects of Model. + 

1. In what computer language* is the model written? 

2., What machine(s) is it ^programmed for? 

,3. How much* time does it take to run? - 

4. Size of model (lines of code, core to run etc.) 

5. How many parameters doe^ model require? 



Validation^of model, 

!• Hat model beea v^li^ted? How? 

2. Hay model been documented? How welL? 

3. Has model been critiqued ob appraised?"* By .whom? 
At what 4 point? 

4. Has there been a sensitivity analysis performed 
' on the model? By whom? 

5. Jan the model by used from current—documentation? 
< , Has it been used? 

Model Use* *. 

1« If asked, how Wtftrld you demonstrate the utility 
' of the model? Have you demonstrated it? 

2. *With whom should one get in touch to discuss 

use of the model? , 

3. How much would *it cost to transfer the model? 

4. Are the model relationships or parameters easy 
1 to use for the user? ^ 

5. Ha^ve there bifen any papers give\i or written on 
the model? Cite references. , 

tKe output, of the model special or is it 
* designed for a general audience? 



5c: 



VII. SUMMARY 

The guidelines on the previous pages should aasi^jfefn . 
the^prep % aration of documentation^ or computer model^^/^Euch 
documentation is primarily a tool for human communication. 
Varying information needs of different -types of rea4^^s such \ 
a& managers, model users, programmers, and analyses are 
accommodated. While managers are often in need of a broad 
spectrum of general information required for decisionmaking, 
users are primarily interested in practical aspects of the 
model and i^ts 'application to the user's specific problems. 
Programmers require technical details which a-re ne^de^d for 
maintenance and modification of the model, while analysts .are 
interested in fhe processing aspects and t^e underlying 
analytical methods an'd • algorithms . By providing sections 
whf&h have been specifically tailored to the viewpoint's of 
diverse readers , ^hum&n communications are enhanced and ' 
differing information needs are satisfied. 1 

T - 

Users of these- guidelines are requested to provide feed- 
back on their use of this document to the authors. It would 
be of x interest how well the .document has served the u-ser's 
needs, what parts have been especially useful, what p^rts were 
not used and why/ and what changes or additions are suggested 
by the readers and users of th^ 4 ocumen t» Such comments would 
be used in future\ revisions . Use of this user experience 
would be of great value to the Federal Modeling Community to 
which this paper is addressed. ' 
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